<?php
/**
 * File management system module with virtual file directories.
 *
 * @author Martin "DevelX" Jurča
 * @version 2009-01-24
 */
interface Files {
    /**
     * Returns category record.
     *
     * @param int $id Category ID.
     * @param boolean $tree When set to true, the result will contain category
     *        and files subtree with selected category as root.
     * @return Array category record. If category does not exists, returns
     *         false.
     */
    public function &getCategory($id, $tree = false);

    /**
     * Saves category. If category already exists, it is rewritten.
     *
     * @param Array $category Category record.
     * @return boolean True on Success, false otherwise.
     */
    public function saveCategory(&$category);

    /**
     * Return all subcategories of specified category as array of category
     * records.
     *
     * @param int $rootId ID of root category
     * @return Array List of subcategories. If root category does not exists,
     *         returns false.
     */
    public function &getCategories($rootId = 0);

    /**
     * Deletes category, all subcategories and files.
     *
     * @param int $id ID of category.
     * @return boolean True on success, false otherwise.
     */
    public function deleteCategory($id);

    /**
     * Returns file record.
     *
     * @param int $id ID of file.
     * @return Array File record. Returns false if the file does not exists.
     */
    public function &getFile($id);

    /**
     * Returs array of all files in specified category.
     *
     * @param int $categoryId ID of category.
     * @return Array List of files. Returns false if the category doeas not
     *         exists.
     */
    public function &getFiles($categoryId);

    /**
     * Saves file record. If the record is already present, it is rewritten.
     *
     * @param Array $file File record.
     */
    public function saveFile(&$file);

    /**
     * Deletes file.
     *
     * @param int $id File ID.
     * @return boolean True on success, false otherwise.
     */
    public function deleteFile($id);

    /**
     * Saves uploaded files.
     *
     * @param Array $files Array with the same structure as $_FILES array.
     * @param int $categoryId ID of category where the files should be saved.
     * @return Array Records of saved files. Returns false on failure.
     */
    public function &uploadFiles(&$files, $categoryId);

    /**
     * Creates mirrors of files by downloading a copy from remote sever and
     * storing it locally and creating record in local database.
     *
     * @param Array $files URLs of remote files.
     * @param int $categoryId ID number of category.
     * @return Array Records of saved files. Returns false on failure.
     */
    public function &mirrorFiles(&$files, $categoryId);
}
?>
